<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Session Class - Usage - Fuel Documentation</title>
	<link href="../../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../../assets/js/nav.js"></script>
	<script type="text/javascript" src="../../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('classes', '../../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>Fuel Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>Session Class</h2>

		<p>
			The session class allows you to maintain state for your application in the stateless environment of the web.
			It allows you to store variables on the server using a variety of storage solutions, and recall these variables on the next page request.
		</p>
		<p>
			The static methods documented on this page use the session driver configured in the configuration via the <kbd>driver</kbd> setting.
			When you have set the <kbd>auto_initialize</kbd> setting to <kbd>true</kbd>, the session will be loaded and initialized when the Fuel framework loads.
			If it is set to <kbd>false</kbd>, it will be loaded automatically as soon as you use one of the methods below.
		</p>
		<p>
			Note that if you choose not to <kbd>auto_initialize</kbd> the session, and you don't use any of the session methods, the session will not be refreshed!
			This can cause unexpected behaviour of your application due to an expired session.
		</p>

		<article>
			<h4 id="method_instance">instance($instance = null)</h4>
			<p>The <strong>instance</strong> method returns the default session instance, or a specific instance, identified by name.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$instance</kbd></th>
								<td><pre class="php"><code>null</code></pre></td>
								<td>Cookiename (as defined in config/session.php) that identifies the required session instance.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>mixed - session object, or false in case the requested instance does not exist.</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// get the default session instance (identified by the 'driver' configuration setting).
$session = Session::instance();

// get a specific session instance
$session = Session::instance('myappcookie');
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_set">set($variable, $value = null)</h4>
			<p>The <strong>set</strong> method allows you to set a session variable.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$name</kbd></th>
								<td><em>required</em></td>
								<td>Name of the session variable to set.</td>
							</tr>
							<tr>
								<th><kbd>$value</kbd></th>
								<td><pre class="php"><code>null</code></pre></td>
								<td>
									The session variables value.<br />
									This can be any data type, but pay attention when storing objects in the session, as session data is serialized, and there are restrictions to serializing an object.
								</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// store the userid in the session
Session::set('userid', $userid);

// you can also store more complex values
Session::set('array', array('varA', 'varB', 'varC' => array('val1', 'val2'));
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_get">get($variable = null, $default = null)</h4>
			<p>The <strong>get</strong> method allows you to retrieve stored variables from the session.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$variable</kbd></th>
								<td><pre class="php"><code>null</code></pre></td>
								<td>Name of the session variable to get. If not specified, all session variables are returned.</td>
							</tr>
							<tr>
								<th><kbd>$default</kbd></th>
								<td><pre class="php"><code>null</code></pre></td>
								<td>Default value to return in case the requested variable does not exist. If no default is given, the method will return <kbd>null</kbd>.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>mixed - Dependent on the type of the stored <var>$variable</var>. The method returns <kbd>null</kbd> if the requested variable does not exist.</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// get the stored userid from the session
$userid = Session::get('userid');
if ( $userid === false )
{
	echo "no user is logged in";
}

// you can retrieve the entire array stored
$arr = Session::get('array');

// or get a specific key from the array
$arr = Session::get('array.varC');

// get all session variables
$vars = Session::get();</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_delete">delete($variable)</h4>
			<p>The <strong>delete</strong> method allows you to delete a stored session variable.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$variable</kbd></th>
								<td><em>required</em></td>
								<td>Name of the session variable to delete.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// delete the stored userid from the session
Session::delete('userid');

// you can also delete a specific key from the array
Session::delete('array.varC');
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_set_flash">set_flash($variable, $value = null)</h4>
			<p>The <strong>set_flash</strong> method allows you to set a session flash variable. Flash variables have a limited lifespan. Depending on the configuration, they will be deleted after the next page request, or after they are retrieved.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$name</kbd></th>
								<td><em>required</em></td>
								<td>Name of the session flash variable to set.</td>
							</tr>
							<tr>
								<th><kbd>$value</kbd></th>
								<td><pre class="php"><code>null</code></pre></td>
								<td>
									The session flash variables value.<br />
									This can be any data type, but pay attention when storing objects in the session, as session data is serialized, and there are restrictions to serializing an object.
								</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// tell the next page request which step to process
Session::set_flash('step', 2);

// you can also store more complex values
Session::set_flash('array', array('varA', 'varB', 'varC' => array('val1', 'val2'));
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_get_flash">get_flash($variable, $default = null)</h4>
			<p>The <strong>get_flash</strong> method allows you to get a session flash variable. Flash variables have a limited lifespan. Depending on the configuration, they will be deleted after the next page request, or after they are retrieved.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$variable</kbd></th>
								<td><em>required</em></td>
								<td>Name of the session variable to get.</td>
							</tr>
							<tr>
								<th><kbd>$default</kbd></th>
								<td><pre class="php"><code>null</code></pre></td>
								<td>Default value to return in case the requested variable does not exist. If no default is given, the method will return <kbd>null</kbd>.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>mixed - Dependent on the type of the stored <var>$variable</var>. The method returns <kbd>null</kbd> if the requested variable does not exist.</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// find out which step to process
$step = Session::get_flash('step');
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_keep_flash">keep_flash($variable)</h4>
			<p>The <strong>keep_flash</strong> method resets a flash variable stored in the session to an 'unrequested' state. This allows you to get a flash variable, and still pass it on to the next page request.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$variable</kbd></th>
								<td><em>required</em></td>
								<td>Name of the flash variable to keep.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// keep the step value for one more page request
Session::keep_flash('step');
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_delete_flash">delete_flash($variable)</h4>
			<p>The <strong>delete_flash</strong> method allows you to delete a stored flash variable.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$variable</kbd></th>
								<td><em>required</em></td>
								<td>Name of the flash variable to delete.</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// delete the step from the session
Session::delete_flash('userid');
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_create">create()</h4>
			<p>The <strong>create</strong> method allows you to create a new session. If a session is already present, it will be destroyed when the new one is created.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>None</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// create a new session
Session::create();
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_destroy">destroy()</h4>
			<p>The <strong>destroy</strong> method allows you to destroy an existing session.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>None</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// destroy a session
Session::destroy();
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_read">read()</h4>
			<p>The <strong>read</strong> method allows you to manually read a session. The session is automatically read when the session class is initialized, so under normal circumstances there is no need to use this method.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>None</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// read the session
Session::read();
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4 id="method_write">write()</h4>
			<p>The <strong>write</strong> method allows you to manually write the session. Under normal circumstances, the session is automatically written when the script ends.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>None</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>void</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php">
<code>// write the session
Session::write();
</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>
